Polaris Web Components Context MCP Tools #20

billfienberg · 2025-05-06T22:58:04Z

TLDR

Polaris Web Components Context MCP Tools

Closes https://github.com/Shopify/admin-ui-foundations/issues/2813

More Context

Add the following MCP tools behind the POLARIS_UNIFIED env var.
- get_started
- read_docs

Tophatting Instructions

In the dev-mcp repo, checkout the bf/mcp-mob-pairing branch and install dependencies
```
dev cd dev-mcp && git checkout bf/mcp-mob-pairing && npm i
```
In the dev-mcp repo, start the inspector
```
npm run inspector
```

Inspector

In your browser, navigate to http://localhost:5173 to access the MCP Inspector.
Click Connect
Click Tools
Click List Tools
Confirm presence/absence of get_started and read_docs tools
- 👀 When the POLARIS_UI=true env var is present, get_started and read_docs should be present.
- 🙈 When the POLARIS_UI=true env var is absent, the get_started and read_docs should be absent.

Cursor

In your terminal, get the absolute path to the version of node you'd like to use.
```
which node
```
- Depending on your node env, this might not be necessary. In my case, Cursor couldn't find my node env.
In Cursor, open Cursor Settings
In Cursor, click MCP Servers
In Cursor, click Add new global MCP server

In .cursor/mcp.json, add the following following JSON

"shopify-dev-mcp-local": {
   "command": "${ABSOLUTE_PATH_TO_NODE} ${PATH_TO_DEV_MCP_PARENT_FOLDER}/dev-mcp/dist/index.js",
   // For example: "command": "/opt/dev/sh/nvm/versions/node/v22.15.0/bin/node /Users/bill/src/github.com/Shopify/dev-mcp/dist/index.js",
   "env": {
     "POLARIS_UI": "true"
   }
 }

Close mcp.json
In Cursor Settings > MCP Servers, confirm that shopify-dev-mcp-local is present and connected
Confirm presence/absence of get_started and read_docs tools
- 👀 When the POLARIS_UI=true env var is present, get_started and read_docs should be present.
- 🙈 When the POLARIS_UI=true env var is absent, the get_started and read_docs should be absent.

Important

If the dev-mcp build changes, then you'll need to click the Refresh button in Cursor Settings > MCP Servers to get the changes.

Screen.Recording.2025-05-12.at.19.40.30.mov

Demo

https://share.descript.com/view/oIyIXvuwZkr

References

https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

billfienberg · 2025-05-09T20:02:28Z

MCP Tools

`get_started`

Promps:

get Started returned App Home overview
Get Started with Admin Extensions returned Admin Extensions overview
Get Started with Checkout Extensions returned Checkout UI Extensions overview
Get Started Customer Account Extensions returned Customer Account UI Extensions overview

Screen.Recording.2025-05-09.at.14.57.57.mov

Experiments

`admin_ui_extensions`

Screen.Recording.2025-05-09.at.15.35.50.mov

`app_home`

Screen.Recording.2025-05-09.at.15.39.22.mov

billfienberg · 2025-05-09T23:31:38Z

.prettierrc

Copied from https://github.com/Shopify/extensibility/blob/main/.prettierrc

billfienberg · 2025-05-09T23:35:05Z

src/tools/index.ts

+    - /docs/api/customer-account-ui-extensions.txt
+    - /docs/api/checkout-ui-extensions.txt
+
+    Whenever the user asks about Polaris web components, shopify functions, or shopify graph ql always use this tool first to provide the most accurate and up-to-date documentation.


Descriptions borrowed from @AaronSpringut's prototype:

https://github.com/shop/PolarisMCP/blob/main/live_docs_server.py

src/tools/index.ts

.prettierrc

src/tools/index.ts

alex-page · 2025-05-14T01:15:34Z

src/tools/index.ts

+
+  if (process.env.POLARIS_UNIFIED) {
+    server.tool(
+      "read_docs",


Should this be named more clearly. This doesn't read_docs it is more like a read_polaris_surface_docs?

Co-Authored-By: Bill Fienberg <[email protected]> Co-Authored-By: AaronSpringut <[email protected]>

alex-page · 2025-05-14T01:27:18Z

Going to ship this. All changes are isolated behind the POLARIS_UNIFIED environment variable. If folks have additional feedback we can fix them in fast follow up PRs.

billfienberg changed the title ~~MCP mob pairing~~ Polaris Context MCP Prototype May 9, 2025

billfienberg commented May 9, 2025

View reviewed changes

.prettierrc Outdated

Copy link

Contributor Author

billfienberg May 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copied from https://github.com/Shopify/extensibility/blob/main/.prettierrc

billfienberg commented May 9, 2025

View reviewed changes

billfienberg marked this pull request as ready for review May 9, 2025 23:35

billfienberg requested a review from a team as a code owner May 9, 2025 23:35

billfienberg assigned Arkham May 12, 2025

billfienberg changed the title ~~Polaris Context MCP Prototype~~ Polaris Web Components Context MCP Tools May 13, 2025

alex-page reviewed May 13, 2025

View reviewed changes

src/tools/index.ts Show resolved Hide resolved

alex-page reviewed May 13, 2025

View reviewed changes

src/tools/index.ts Outdated Show resolved Hide resolved

alex-page reviewed May 13, 2025

View reviewed changes

src/tools/index.ts Outdated Show resolved Hide resolved

alex-page reviewed May 13, 2025

View reviewed changes

.prettierrc Outdated Show resolved Hide resolved

alex-page mentioned this pull request May 13, 2025

Add watch script #22

Merged